Developer CD Series 1996 April: Mac OS SDK/Dev.CD Apr 96 SDK/Dev.CD Apr 96 SDK1.toast/Development Kits (Disc 1)/OpenDoc Development Framework/ODFDev/ODF/Found/FWString/Include/FWStrs.h

Text File | 1995-11-08 | 22.3 KB | 682 lines | [TEXT/MPS ]

//========================================================================================
//
//    File:                FWStrs.h
//    Release Version:    $ 1.0d11 $
//
//    Copyright:    (c) 1993, 1995 by Apple Computer, Inc., all rights reserved.
//
//========================================================================================

#ifndef FWSTRS_H
#define FWSTRS_H

#ifndef FWSTDDEF_H
#include "FWStdDef.h"
#endif

#ifndef FWEXCDEF_H
#include "FWExcDef.h"
#endif

#ifndef FWCHARIT_H
#include "FWCharIt.h"
#endif

#ifndef FWCHARAC_H
#include "FWCharac.h"
#endif

#if FW_LIB_EXPORT_PRAGMAS
#pragma lib_export on
#endif

//========================================================================================
// Forward Declarations
//========================================================================================

class FW_CLASS_ATTR FW_CStringReader;
class FW_CLASS_ATTR FW_CStringWriter;
class FW_CLASS_ATTR FW_CStringTool;
class FW_CLASS_ATTR FW_CStringArchiver;

//========================================================================================
//    CLASS FW_CByteString
//
//    String class implementations must satisfy the following requirements:
//
//    1) The string representation is kept in memory.
//    2) The string representation is contiguous.
//    3) The string is NUL-terminated.
//
//    FW_CByteString is an abstract base class that knows about bytes only, not characters.
//========================================================================================

class FW_CLASS_ATTR FW_CByteString FW_AUTO_DESTRUCT_OBJECT
{
 public:

    FW_DECLARE_CLASS

    virtual ~ FW_CByteString();
    FW_CByteString();
    FW_CByteString(const FW_CByteString &string);

    FW_Byte* BytePositionInString(FW_ByteCount position);

    FW_ByteCount GetByteLength() const;

    FW_ByteCount GetCapacity() const;

    virtual FW_ByteCount GrowCapacity(FW_ByteCount capacityNeeded) = 0;
        // Expand the string, if necessary, to capacityNeeded.
        // Return the new capacity of the string, which may be less than capacityNeeded!
        // The capacity of a string is never reduced (except by deleting the string).

    void Export(char* buffer) const;
        // Copy contents of this string to external buffer.
        // buffer will contain nul-terminated string.
        // It is client's responsibility to ensure buffer is large enough.

 protected:

    virtual void PrivSetByteLength(FW_ByteCount bytes);

    void PrivNullTerminate();
        // Append null byte to end of string

    void AppendBytes(const FW_Char* source, FW_ByteCount numberBytes);

    void DeleteBytes(FW_ByteCount numberBytes, FW_ByteCount position);
        // Delete numberBytes bytes, starting at position.

    void InsertBytes(const FW_Char* bytes,
                     FW_ByteCount numberBytes,
                     FW_ByteCount position);

    virtual void ReplaceAllBytes(const FW_Char* string, FW_ByteCount numberBytes);

    void ReplaceBytes(const FW_Char* source,
                      FW_ByteCount numberBytes,
                      FW_ByteCount position);

    void RetrieveBytes(FW_Char* destination,
                       FW_ByteCount numberBytes,
                       FW_ByteCount position) const;

    void TruncateBytes(FW_ByteCount numberBytes);


    FW_Byte*        fRepresentation;

    FW_ByteCount    fByteLength;
        // Cached length in bytes.
        // Must always be kept up to date, since GetByteLength is nonvirtual inline.
        // Set by DeleteBytes, InsertBytes, ReplaceBytes

    FW_ByteCount    fCapacity;
        // Cached capacity.
        // Must always be kept up to date, since GetCapacity is nonvirtual inline.

};

//========================================================================================
//    CLASS FW_CString
//
//    Characters in strings may occupy one, two, and possibly more bytes.
//  The number of characters in the string is therefore not necessarily equal
//    to the number of bytes in the string. The field fCharWidth gives the number
//    of bytes per character for a particular string. FW_CString assumes that all
//    characters in a string are the same width. In order to mix character sizes
//    in a string, FW_CString must be subclassed.
//
//    The "length" of the string is measured in characters.
//  The "byteLength" of the string is measured in bytes.
//  The "capacity" of the string is measure in bytes.
//
//========================================================================================

class FW_CLASS_ATTR FW_CString : public FW_CByteString
{
  public:

    friend class FW_CLASS_ATTR FW_CStringReader;
    friend class FW_CLASS_ATTR FW_CStringWriter;
    friend class FW_CLASS_ATTR FW_CStringTool;
    friend class FW_CLASS_ATTR FW_CStringArchiver;

    FW_DECLARE_CLASS

    virtual ~ FW_CString();
    FW_CString();
    FW_CString(const FW_CString &string);
    FW_CString(FW_ByteCount charWidth);

    FW_CString& operator=(const FW_CString& string);
    FW_CString& operator=(const FW_Char* string);

    FW_CharacterCount GetLength() const;

    FW_ByteCount GetCharWidth() const;

    operator const FW_Char*() const;
        // Return a pointer to the first character in the string.
        // Strings must be contiguous storage, and NUL-terminated!

    FW_Char operator[](FW_CharacterPosition position) const;
        // Retrieve character at given position.
        // Cannot be used on LHS of assignment.
        // The NUL-terminator at position=fLength cannot be accessed.

    void Retrieve(FW_Char* destination,
                  FW_CharacterCount numberChars,
                  FW_CharacterPosition position) const;
        // Retrieve numberChars of characters starting at position.
        // Copy characters into the destination.

    void Delete(FW_CharacterCount numberChars,
                FW_CharacterPosition position);
        // Delete numberChars characters, starting at position.

    void Replace(const FW_Char* source,
                 FW_CharacterCount numberChars,
                 FW_CharacterPosition position);
        // Replace numberChars of characters starting at position with the source.
        // The client must ensure that the source characters are the same width as
        // those in the string.

    void Insert(const FW_Char* chars,
                FW_CharacterCount numberChars,
                FW_CharacterPosition position);
        // Insert characters into string just before the character at positition.
        // Insert at position GetLength() appends the characters.
        // Insert at position 0 prepends the characters.

    void Insert(const FW_CString &string, FW_CharacterPosition position);
        // Insert string at position.

    void ReplaceAll(const FW_CString &string);
        // Replace entire contents of this string with string.

    void ReplaceAll(const FW_Char* items, FW_CharacterCount numberItems);
        // Replace entire contents of this string with items.

    void ReplaceAll(const FW_Char* string);
        // Replace entire contents of this string with (nul-terminated) string.

    void Append(const FW_CString &string);
        // Append string onto end of this string.

    void Append(const FW_Char* items, FW_CharacterCount numberItems);
        // Append items onto end of this string.

    void Append(const FW_Char* string);
        // Append (nul-terminated) string onto end of this string.

    void Append(FW_Char character);
    void Append(FW_WChar character);
        // Append a single character onto the end of this string.
        // Use the FW_WChar version for double-byte characters

    void Prepend(const FW_Char* items, FW_CharacterCount numberItems);
        // Prepend items onto beginning of this string.

    void Prepend(const FW_CString &string);
        // Prepend string onto beginning of this string.

    void Truncate(FW_CharacterPosition position);
        // Truncate string at position.  Truncate(0) clears string.

    FW_CString& operator+=(const FW_CString &string);
        // Append string onto the end of this string.

    FW_CString& operator+=(const FW_Char* items);
        // Append (nul-terminated) items onto the end of this string.

    FW_CString& operator+=(FW_Char character);
    FW_CString& operator+=(FW_WChar character);
        // Append a single character onto the end of this string.
        // Use the FW_WChar version for double-byte characters

    // ----- StringTool functions, passed through to current StringTool
    //       These functions are convenience functions only, and will
    //         work correctly only if both strings are of the same locale.

    void ToUpper();
    void ToLower();

    FW_Boolean Substitute(const FW_CString &searchString,
                          const FW_CString &substitutionString);

    FW_Boolean FindSubString(const FW_CString &subString,
                             FW_CharacterPosition &foundPosition,
                             FW_CharacterPosition startPosition=0) const;

    FW_Boolean FindCharacter(FW_Char character,
                             FW_CharacterPosition &foundPosition,
                             FW_CharacterPosition startPosition=0) const;
    FW_Boolean FindCharacter(FW_LChar character,
                             FW_CharacterPosition &foundPosition,
                             FW_CharacterPosition startPosition=0) const;

    FW_Boolean FindWhiteSpace(FW_CharacterPosition &foundPosition,
                              FW_CharacterPosition startPosition=0) const;

    FW_Boolean FindNonWhiteSpace(FW_CharacterPosition &foundPosition,
                                 FW_CharacterPosition startPosition=0) const;

    FW_Boolean operator==(const FW_CString &string) const;
    FW_Boolean operator==(const char *string) const;
    FW_Boolean operator!=(const FW_CString &string) const;
    FW_Boolean operator!=(const char *string) const;
    FW_Boolean operator<(const FW_CString &string) const;
    FW_Boolean operator<(const char *string) const;
    FW_Boolean operator>(const FW_CString &string) const;
    FW_Boolean operator>(const char *string) const;
    FW_Boolean operator<=(const FW_CString &string) const;
    FW_Boolean operator<=(const char *string) const;
    FW_Boolean operator>=(const FW_CString &string) const;
    FW_Boolean operator>=(const char *string) const;

#ifdef FW_BUILD_MAC
  public:

    // ----- 'Pascal' strings for Macintosh toolbox

    void ExportPascal(FW_PascalChar* buffer) const;
        // Copy contents of this string to external 'Pascal' buffer.
        // buffer will contain Pascal string with length byte at buffer[0].
        // It is client's responsibility to ensure buffer is large enough.

    void ReplaceAll(const FW_PascalChar* string);
        // Replace entire contents of this string with pascal string.
#endif

    virtual FW_ByteCount CharsToBytes(FW_CharacterCount numberChars,
                                      FW_CharacterPosition position,
                                      FW_ByteCount& bytePosition) const;
        // Convert a character count and position to byte values.
        // Client should override for strings with mixed-size characters.

  protected:

    virtual void ReplaceAllBytes(const FW_Char* string, FW_ByteCount numberBytes);

    virtual void PrivSetLength(FW_CharacterCount characters,
                               FW_ByteCount bytes,
                               FW_ByteCount charWidth);

    void PrivSetLength(FW_CharacterCount characters, FW_ByteCount bytes);
    void PrivSetLength(FW_CharacterCount characters);

    FW_Byte* GetBytePosition(FW_CharacterPosition position) const;
        // Return a pointer to the specified character position in the string.


    FW_CharacterCount    fLength;
        // Cached length.
        // Must always be kept up to date, since GetLength is nonvirtual inline.

    FW_ByteCount fCharWidth;
        // Width of a character in bytes. Default value is sizeof(FW_Char) = 1.

  private:

    int Compare(const FW_CString &string) const;
        // An implementation method.  Clients use comparison operators.

};

//========================================================================================
//    CLASS FW_CDynamicString
//========================================================================================

class FW_CLASS_ATTR FW_CDynamicString : public FW_CString
{
  public:

    FW_DECLARE_CLASS

    virtual ~ FW_CDynamicString();
    FW_CDynamicString(FW_ByteCount capacity=0);
    FW_CDynamicString(FW_ByteCount capacity, FW_ByteCount charWidth);
    FW_CDynamicString(const FW_CDynamicString &string);
    FW_CDynamicString(const FW_CString &string);
    FW_CDynamicString(const FW_Char *items, FW_CharacterCount numberItems);
    FW_CDynamicString(const FW_Char *items);

    FW_CString& operator=(const FW_CDynamicString &string);
    FW_CString& operator=(const FW_CString& string);
    FW_CString& operator=(const FW_Char* string);

    virtual FW_ByteCount GrowCapacity(FW_ByteCount capacityNeeded);
        // Expand the string, if necessary to capacityNeeded.
        // Return the new capacity of the string.
        // The capacity of a string is never reduced (except by deleting the string).

  protected:

    void PrivResize(FW_ByteCount newCapacity);

  private:

    void AllocateRepresentation(FW_ByteCount capacity);
};

//========================================================================================
//    CLASS FW_CStringReader
//========================================================================================

class FW_CLASS_ATTR FW_CStringReader : public FW_CTextReader
{
  public:
    FW_CStringReader(const FW_CString &string);
    FW_CStringReader(const FW_CString &string,
                     FW_BytePosition start,
                     FW_ByteCount length);
    virtual ~ FW_CStringReader();

  protected:

    virtual void DoGetNextBuffer();
        // Get another buffer from text data structure.
        // Updates fStart and fLimit.
        // Must ensure that fStart<=fLimit

    virtual void DoGetPreviousBuffer();
        // Gets previous buffer from text data structure.
        // Updates fStart and fLimit.
        // Must ensure that fStart<=fLimit

};

//========================================================================================
//    CLASS FW_CStringWriter
//========================================================================================

class FW_CLASS_ATTR FW_CStringWriter : public FW_CTextWriter
{
  public:
    enum {kDefaultBufferSize=32};

    virtual ~ FW_CStringWriter();
    FW_CStringWriter(FW_CString &string,
                     FW_TextWriterMode mode=FW_kTextAppend,
                     unsigned short bufferSize=kDefaultBufferSize);

  protected:

    virtual void DoFlushBuffer(FW_ByteCount bytesToFlush);    // Override
        // Flush the current buffer.

    virtual void DoGetNextBuffer();    // Override
        // Get another buffer from string, update fNext and fLimit.


    FW_CString&            fString;
    unsigned short        fBufferSize;
    FW_TextWriterMode    fMode;            // FW_kTextWriteOver or FW_kTextAppend
    FW_Byte*            fBuffer;
};

//========================================================================================
//    CLASS FW_CByteString inlines
//========================================================================================

//----------------------------------------------------------------------------------------
//    FW_CByteString::BytePositionInString
//----------------------------------------------------------------------------------------

inline FW_Byte* FW_CByteString::BytePositionInString(FW_ByteCount position)
{
    return fRepresentation + position;
}

//----------------------------------------------------------------------------------------
//    FW_CByteString::Export
//----------------------------------------------------------------------------------------

inline void FW_CByteString::Export(FW_Char* buffer) const
{
    FW_ASSERT(buffer != NULL);
    FW_BlockMove(fRepresentation, (FW_Byte*) buffer, fByteLength+sizeof(FW_Char));
}

//----------------------------------------------------------------------------------------
//    FW_CByteString::GetByteLength
//----------------------------------------------------------------------------------------

inline FW_ByteCount FW_CByteString::GetByteLength() const
{
    return fByteLength;
}

//----------------------------------------------------------------------------------------
//    FW_CByteString::GetCapacity
//----------------------------------------------------------------------------------------

inline FW_ByteCount FW_CByteString::GetCapacity() const
{
    return fCapacity;
}

//----------------------------------------------------------------------------------------
//    FW_CByteString::PrivNullTerminate
//----------------------------------------------------------------------------------------

inline void FW_CByteString::PrivNullTerminate()
{
    *((FW_Char*)(fRepresentation+fByteLength)) = FW_kNulCharacter;
}

//========================================================================================
//    CLASS FW_CString inlines
//========================================================================================

//----------------------------------------------------------------------------------------
//    FW_CString::GetBytePosition
//----------------------------------------------------------------------------------------

inline FW_Byte* FW_CString::GetBytePosition(FW_CharacterPosition position) const
{
    return (FW_Byte*)(fRepresentation + position*fCharWidth);
}

//----------------------------------------------------------------------------------------
//    FW_CString::GetCharWidth
//----------------------------------------------------------------------------------------

inline FW_ByteCount FW_CString::GetCharWidth() const
{
    return fCharWidth;
}

//----------------------------------------------------------------------------------------
//    FW_CString::GetLength
//----------------------------------------------------------------------------------------

inline FW_CharacterCount FW_CString::GetLength() const
{
    return fLength;
}

//----------------------------------------------------------------------------------------
//    FW_CString::PrivSetLength
//----------------------------------------------------------------------------------------

inline void FW_CString::PrivSetLength(FW_CharacterCount characters)
{
    fLength = characters;
}

inline void FW_CString::PrivSetLength(FW_CharacterCount characters, FW_ByteCount bytes)
{
    fLength = characters;
    PrivSetByteLength(bytes);    // ensures string is null-terminated
}


//----------------------------------------------------------------------------------------
//    FW_CString::operator const FW_Char*
//----------------------------------------------------------------------------------------

inline FW_CString::operator const FW_Char*() const
{
    return (const FW_Char*) fRepresentation;
}

#ifdef FW_BUILD_MAC
//----------------------------------------------------------------------------------------
//    FW_CString::ExportPascal
//----------------------------------------------------------------------------------------

inline void FW_CString::ExportPascal(FW_PascalChar* buffer) const
{
    FW_ASSERT(buffer != NULL);
    FW_BlockMove(fRepresentation, (FW_Byte*)(buffer+1), fLength);
    buffer[0] = (FW_PascalChar) fLength;
}
#endif

#ifdef FW_BUILD_MAC
//----------------------------------------------------------------------------------------
//    FW_CString::ReplaceAll
//----------------------------------------------------------------------------------------

inline void FW_CString::ReplaceAll(const FW_PascalChar* items)
{
    ReplaceAllBytes((const FW_Char*)items+1, items[0]);
}
#endif

//----------------------------------------------------------------------------------------
//    FW_CString::Insert
//----------------------------------------------------------------------------------------

inline void FW_CString::Insert(const FW_CString& string, FW_CharacterPosition position)
{
    FW_ASSERT(string.GetCharWidth() == fCharWidth);
    Insert(string, string.GetLength(), position);
}

//----------------------------------------------------------------------------------------
//    FW_CString::Append
//----------------------------------------------------------------------------------------

inline void FW_CString::Append(const FW_CString& string)
{
    FW_ASSERT(string.GetCharWidth() == fCharWidth);
    Insert(string, string.GetLength(), fLength);
}

//----------------------------------------------------------------------------------------
//    FW_CString::Append
//----------------------------------------------------------------------------------------

inline void FW_CString::Append(const FW_Char* items, FW_CharacterCount numberItems)
{
    Insert(items, numberItems, fLength);
}

//----------------------------------------------------------------------------------------
//    FW_CString::Append
//----------------------------------------------------------------------------------------

inline void FW_CString::Append(const FW_Char* string)
{
    Insert(string, FW_StringLength(string), fLength);
}

//----------------------------------------------------------------------------------------
//    FW_CString::Append
//----------------------------------------------------------------------------------------

inline void FW_CString::Append(FW_Char character)
{
    FW_ASSERT(fCharWidth == sizeof(FW_Char));
    Insert(&character, 1, fLength);
}

inline void FW_CString::Append(FW_WChar character)
{
    FW_ASSERT(fCharWidth == sizeof(FW_WChar));
    Insert((const FW_Char*)&character, 1, fLength);
}

//----------------------------------------------------------------------------------------
//    FW_CString::Prepend
//----------------------------------------------------------------------------------------

inline void FW_CString::Prepend(const FW_Char* items, FW_CharacterCount numberItems)
{
    Insert(items, numberItems, 0);
}


//----------------------------------------------------------------------------------------
//    FW_CString::Prepend
//----------------------------------------------------------------------------------------

inline void FW_CString::Prepend(const FW_CString& string)
{
    FW_ASSERT(string.GetCharWidth() == fCharWidth);
    Insert(string, string.GetLength(), 0);
}


//----------------------------------------------------------------------------------------
//    FW_CString::operator+=
//----------------------------------------------------------------------------------------

inline FW_CString& FW_CString::operator+=(const FW_CString& string)
{
    Append(string);
    return *this;
}

//----------------------------------------------------------------------------------------
//    FW_CString::operator+=
//----------------------------------------------------------------------------------------

inline FW_CString& FW_CString::operator+=(const FW_Char* string)
{
    Append(string);
    return *this;
}

//----------------------------------------------------------------------------------------
//    FW_CString::operator+=
//----------------------------------------------------------------------------------------

inline FW_CString& FW_CString::operator+=(FW_Char character)
{
    Append(character);
    return *this;
}

inline FW_CString& FW_CString::operator+=(FW_WChar character)
{
    Append(character);
    return *this;
}

//========================================================================================
//    CLASS FW_CDynamicString inlines
//========================================================================================

//----------------------------------------------------------------------------------------
//    FW_CDynamicString::AllocateRepresentation
//----------------------------------------------------------------------------------------

inline void FW_CDynamicString::AllocateRepresentation(FW_ByteCount capacity)
{
    fRepresentation = new FW_Byte[capacity+FW_kMedianCharacterSize];
    fCapacity=capacity;
    PrivSetLength(0,0);
}

#if FW_LIB_EXPORT_PRAGMAS
#pragma lib_export off
#endif

#endif